home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / AUDIOPLAYERS / AMP / !Amp / Docs / AMPlayer next >
Text File  |  1999-09-26  |  14KB  |  390 lines

  1.  
  2.                                     AMPlayer
  3.                                     --------
  4.  
  5.  
  6. This is a module for playing Audio MPEG files through the computer sound
  7. output. It will select the 8 or 16 bit output depending on the normal
  8. configuration (and availability).
  9.  
  10.  
  11. AMPlayer module
  12. ===============
  13.  
  14. This is the program that does the actual work. There are various reasons for
  15. wanting to control the module directly instead of through the frontend:
  16. 1. You get better control, and can automate things using obey files, etc.
  17. 2. You may want to write your own frontend.
  18. 3. The fancy frontend uses memory and CPU time that might be better used
  19.    elsewhere.
  20.  
  21. For these purposes, the module has several *commands and SWIs.
  22.  
  23. * Commands
  24. ==========
  25.  
  26. *AMPlay starts playing an Audio MPEG file. When -Q[ueue] is present, the file
  27. will be played after the current one finishes, otherwise immediately.
  28. When -C[ue] is present, the file will be started, but with the player in pause
  29. mode.
  30. Syntax: *AMPlay [-Queue|-Cue] <filename>
  31.  
  32. *AMStop stops the MPEG file playing
  33. Syntax: *AMStop
  34.  
  35. *AMInfo prints information about the player module status, and about the file
  36. playing, if any.
  37. Syntax: *AMInfo
  38.  
  39. *AMVolume sets the playback volume. Range is 0 to 127, with 113 as initial
  40. value.
  41. Syntax: *AMVolume <number>
  42.  
  43. *AMLocate locates the specified point in the file currently playing/paused.
  44. Syntax: *AMLocate <hours>[:<minutes>[:<seconds>]]
  45.  
  46.  
  47. System variables
  48. ================
  49.  
  50. AMPlayer$Buffer$*
  51. -----------------
  52. You can set up the audio buffer size to use by setting one or more of these
  53. variables. When the buffer is created, the size is determined by the best
  54. match of the filename and one of these variables. The more characters that
  55. match, the better, and the variable with the most will control the buffer
  56. size.
  57. The idea is that the best buffer size somewhat depends on the file access
  58. speed. The faster the device, the smaller buffer you can get away with, and
  59. the better response you will get from things like fast forward/rewind.
  60. CDFS for example is very slow. Therefore, I have the following variables:
  61. AMPlayer$Buffer$    20
  62. AMPlayer$Buffer$SCSI    16
  63. AMPlayer$Buffer$CDFS    40
  64.  
  65. The effect of this is, that CDFS in general will get size 40. SCSI is fast
  66. and gets 16, and everything else (ADFS, RAMFS etc.) get 20.
  67. It is possible (but not necessary in my case) to include part of the disc
  68. name too (e.g. "AMPlayer$Buffer$ADFS::Winnie"), to make the buffer size
  69. depend on the drive as well as the FS. Indeed, you can go further and
  70. include some directory path as well, though that will probably be rarely
  71. used (with softlinks perhaps?).
  72.  
  73. The size is given in "blocks". These are currently about 4.5K. The reason
  74. for not giving it in Kbytes is, that it is highly likely that the buffer
  75. requirement will change (decrease) in later versions, while still having
  76. the same resulting buffer time. Giving it in blocks means you don't have
  77. to change the value when the block size changes.
  78.  
  79.  
  80. AMPlayer$FileBuffer
  81. -------------------
  82. If this variable is set, it is used to decide the size of the input buffer.
  83. On slow filing systems, the sound may mute while fetching more data. Raising
  84. the input buffer size will help. The size is given in kbytes. If the variable
  85. doesn't exist, the default size is 32K.
  86.  
  87.  
  88. AMPlayer$Volume
  89. ---------------
  90. Setting this to some value between 0 and 127, will determine the default
  91. volume when the module is later loaded. It only has effect before loading;
  92. to change the volume afterwards, use *AMVolume.
  93. If unset, volume 113 is used at startup.
  94.  
  95.  
  96. SWI calls
  97. =========
  98.  
  99. SWI AMPlayer_Play
  100. -----------------
  101. On entry    R0 = Flags
  102.              bit0    Queue only
  103.              bit1    Cue
  104.         R1 ->Filename
  105.  
  106. On exit        All registers preserved
  107.  
  108. Bit0,1 of R0 determines the action:
  109. 0    Starts playing the file immediately, after stopping any other file
  110.     currently playing.
  111. 1    Registers the filename as "next" file (see File info block below).
  112.     The file will start when the current one finishes normally (i.e. not
  113.     if it is stopped by an explicit call to AMPlayer_Stop or *AMStop).
  114.     If there is no file currently playing, the behaviour is exactly as
  115.     with bit0 of R0 clear.
  116. 2    Starts the file immediately, but frozen at frame 0 in pause mode.
  117.     Use SWI AMPlayer_Pause to start playback (which will start with a
  118.     very much shorter delay than if just using Play).
  119. 3    Currently undefined.
  120.  
  121. Note: There can only be one "next" file at any moment. The name registered
  122.       can safely be changed to something else, just by calling this SWI again.
  123.       It is possible to cancel the registered file by calling this SWI with
  124.       bit0 of R0 set, and R1 pointing to a null string.
  125.  
  126. Note: Given sufficient playback buffer and medium access speed, the current
  127.       file will continue seamlessly into the next one. This is good for live
  128.       music, that has been divided into separate files.
  129.  
  130.  
  131. SWI AMPlayer_Stop
  132. -----------------
  133. On entry    R0 = Flags
  134.              bit0    Cut to next file
  135.  
  136. On exit        All registers preserved
  137.  
  138. Stops playback. If bit0 of R0 is set, playback continues with a queued file
  139. if any.
  140.  
  141.  
  142. SWI AMPlayer_Pause
  143. ------------------
  144. On entry    R0 = Flags
  145.              bit0    Continue
  146.  
  147. On exit        All registers preserved
  148.  
  149. Action is determined by bit0 of R0:
  150. 0    Halts playback immediately.
  151. 1    Continues playback immediately.
  152.  
  153. Pause mode may also be cancelled by stopping. If Stop is used to cut to the
  154. next file, or if a different file is started, pause mode will continue to
  155. be in effect, freezing the new file at time=0. This can be used to ensure
  156. that playback starts at the instant of calling AMPlayer_Pause (as opposed to
  157. calling AMPlayer_Play, which can have a delay while opening the file etc.)
  158.  
  159.  
  160. SWI AMPlayer_Locate
  161. -------------------
  162. On entry    R0 = Flags
  163.         R1 = Target time
  164.  
  165. On exit        All registers preserved
  166.  
  167. Locates the position of the target time, and continues playback (or pausing)
  168. from there.
  169. This has no effect unless the status is either Playing, Locating or Paused.
  170. This may take some time, and the playback buffer may empty (which will mute
  171. the sound).
  172. The time given here corresponds to the elapsed time returned from
  173. AMPlayer_Info below. This is true even when the elapsed time is wrong (see
  174. below). So when, at time X, the Info call returns the wrong time Y, giving
  175. time Y to this call will still start playing at the right time X.
  176. Playback can only start on a frame boundary, so the resolution of the start
  177. point is around 2 cs (for 128kbit/sec, 44.1kHz frames).
  178.  
  179.  
  180. SWI AMPlayer_Info
  181. -----------------
  182. On entry    R0 = Flags
  183.  
  184. On exit        R0 = Player status
  185.         Other registers depend on status, as follows:
  186.             Status        Info
  187.         R0=0    Dormant        None
  188.         
  189.         R0=1    Starting    R1 ->Filename
  190.         
  191.         R0=2    Locating    R1 ->Filename
  192.                     R2 ->File info block (see below)
  193.                     R3 ->Frame info block (see below)
  194.                     R4 = Target time
  195.         
  196.         R0=3    Playing        R1 ->Filename
  197.                     R2 ->File info block
  198.                     R3 ->Frame info block
  199.         
  200.         R0=4    Paused        R1 ->Filename
  201.                     R2 ->File info block
  202.                     R3 ->Frame info block
  203.         
  204.         R0=5    Stopping    R1 ->Filename
  205.         
  206.         R0=6    Changing    R1 ->New filename
  207.         
  208.         R0=7    Cueing        R1 ->Filename
  209.  
  210. Note: When locating, the current time can be read from the file info block,
  211.       as it moves toward the target time returned in R4.
  212.       
  213. Note: The registers not mentioned above are preserved. This provides an easy
  214.       way of determining the info returned, without decoding R0. In Basic:
  215.       SYS "AMPlayer_Info",,"" TO ,Filename$,FIB%
  216.       This will set Filename$ to either "" or the filename. Similarily, FIB%
  217.       will be 0 if there is no info at this stage, or a pointer to it if there
  218.       is.
  219.  
  220. Note: There is a brief period when the status might be returned as 2 or 3, but
  221.       where there is no valid frame info block, because the first frame hasn't
  222.       been read. In that case, R3 will be preserved, so the code mentioned
  223.       above will still work.
  224.  
  225.  
  226. SWI AMPlayer_Control
  227. --------------------
  228. On entry    R0 = Reason code
  229.         Other registers depend on code:
  230.         R0=0    Read/write main volume
  231.             R1 = New volume (0-127), or -1 to read
  232.             On exit:
  233.             R1 = Old volume
  234.  
  235.         R0=1    Read/write size of audio buffer
  236.             R1 = New size in bytes, or -1 to read
  237.             On exit:
  238.             R1 = Old size
  239.             
  240.             If the buffer isn't currently created, this controls
  241.             how large it will be when it eventually is.
  242.             If it exists, OS_ChangeDynamicArea is used to change
  243.             the size. This may fail with an error, even if some
  244.             of the job was done (this can happen when reducing the
  245.             size, as the amount that can be released depends on
  246.             what is currently being played).
  247.             If it succeeds, the sound will be broken up at least
  248.             once. So it is best to set the size while not playing.
  249.  
  250.         R0=2    Set stack check level
  251.             R1 = New level (in words), or 0 for default
  252.             
  253.             When receiving a callback, the SVC stack depth is
  254.             checked to see if the kernel is reasonably unthreaded.
  255.             By using this call, you can control what is considered
  256.             "reasonable". The default value is currently 64, i.e.
  257.             if there are more than 64 words on the stack by the
  258.             time of the callback, a new callback will be registered
  259.             later instead. Setting this too low will cause the
  260.             player to stall, and you can only stop it by killing
  261.             the module.
  262.  
  263.  
  264. Returned structures
  265. ===================
  266.  
  267. File info block
  268. ---------------
  269. Offset    Meaning
  270. 0    Flags:
  271.     bit0 set: Total time valid
  272.     bit1 set: Elapsed time valid
  273.     bit2 set: ID3 tag info pointers valid
  274.     bit3 set: VU values valid
  275.     bit4 set: Error message pointer valid
  276.     bit5 set: Next filename pointer valid
  277.     bit6-31 reserved
  278. 4    Buffer usage ratio in %
  279. 8    Projected total time in cs if bit0 of flags set (see below)
  280. 12    Time elapsed in cs if bit1 of flags set
  281. 16    Pointer to ID3 song title if bit2 of flags set (see below)
  282. 20    Pointer to ID3 artist if bit2 of flags set
  283. 24    Pointer to ID3 album name if bit2 of flags set
  284. 28    Pointer to ID3 year string if bit2 of flags set
  285. 32    Pointer to ID3 comment if bit2 of flags set
  286. 36    Left channel VU if bit3 set (see below)
  287. 40    Right channel VU if bit3 set
  288. 44    Main volume (0..127)
  289. 48    Pointer to most recent error/warning message if bit4 of flags set
  290. 52    Pointer to filename of the "next" file if bit 5 of R0 is set
  291. 56    ID3 genre (a number) if bit2 of flags set
  292.  
  293. Note: All the string-pointers are addresses of 0-terminated strings, which are
  294.       to be read only. If you want to keep on referring to the same string,
  295.       copy it into your own workspace. The ones pointed to can and will change
  296.       according to the 'state of play'. This is not true for all of them, so
  297.       don't rely on that either (i.e. call the SWI when you want to update
  298.       your view of the current status). Also, it's important to check the
  299.       appropriate flag bit before referring to any pointers. Not doing so can
  300.       result in a program that seems to work, but fails in mysterious ways
  301.       once in a while.
  302.  
  303. Note: The projected total time is correct if the current frame type (bitrate,
  304.       etc.) stays constant until the end of the file. It will be wrong if
  305.       either
  306.       1. the file size is unknown, e.g. if playing a stream, or
  307.       2. the frame type will later change in a way that alters the number of
  308.          bytes per frame.
  309.       None of the above exceptions are true in the vast majority of mpeg files.
  310.       The first case is determined by the module, and bit0 of the flags will
  311.       be clear. The second case cannot be known in advance, and it will also
  312.       affect the elapsed time. No matter what happens, the time will always
  313.       move forward, it just might not be counting centiseconds in these cases.
  314.  
  315. Note: Any of the ID3 tag strings may be null, indeed, the often are. This
  316.       indicates that the tag field consists entirely of spaces.
  317.  
  318. Note: When the VU level is available, it is a number between 0 and 255. The
  319.       value is from -42 to 0 dB, in 1/6th dB steps. The level is the peak of
  320.       the average level since last calling this SWI.
  321.  
  322. Frame info block
  323. ----------------
  324. Offset    Meaning
  325. 0    MPEG version as 3 ASCII chars and a 0 terminator, e.g. "2.0"
  326. 4    Layer type (1..3). 0 is unknown layer
  327. 8    Sampling frequency in Hz
  328. 12    Bitrate in kbit/sec
  329. 16    Mode
  330.     0: Stereo
  331.     1: Joint-stereo
  332.     2: Dual channel
  333.     3: Single channel
  334. 20    Number of channels
  335. 24    Flags
  336.     bit0: Copyright
  337.     bit1: Original
  338.     bit2: CRC
  339. 28    Pointer to left channel DCT array
  340. 32    Pointer to right channel DCT array
  341.  
  342.  
  343. Credits
  344. =======
  345.  
  346. I have no documentation about the Audio MPEG format. So this module was
  347. produced by porting several other free mpeg decoders, extracting the
  348. necessary bits, then optimising it for RISC OS/ARM. The latter by rewriting
  349. the algorithms in most cases. Therefore, there are concepts and code bits
  350. by many different people left in this module. I will try to list the most
  351. obvious "contributors", as I could certainly not have done it without access
  352. to their work:
  353.  
  354. Michael Hipp & Oliver Fromme wrote mpg123, which was ported and used.
  355. Tomislav Uzelac wrote "amp", similarily ported and learned from.
  356. ISO MPEG Audio Subgroup Software Simulation Group, dist10 package was used
  357. as the main source of information about the intended functionality, rather
  358. than the actual implementation of it.
  359.  
  360. And thanks must go to the testers that put up with the early bugs
  361. (in order of appearance)...
  362. Gerph, Kira, unCiscy, JanM, Zhadnost, Cocodude, MoZes, Lennier, Xargle,
  363. Ben, TwoFlower, Forrey, & Nick.
  364.  
  365. License
  366. =======
  367.  
  368. I don't speak Legalese, so if any lawyers have trouble understanding the
  369. following, please ask a grownup for help.
  370.  
  371. In its current form, this is free for copying and use by anyone, subject to
  372. the following:
  373. If you want to include any of this as part of a commercial product, you need
  374. my permission.
  375. It can be freely supplied with PD, Freeware, and similar programs, as long as
  376. proper credit is given, and no money is charged for them in any way.
  377.  
  378. At some point, I will include the source, and this licence will probably be
  379. replaced with the GPL, but that will not affect the status of previous
  380. versions.
  381.  
  382.  
  383. Contact
  384. =======
  385.  
  386. Questions, etc. should be addressed to:
  387.  
  388. Thomas Olsson
  389. tolsson@isa.dknet.dk
  390.